Summary

Changes useAgentChat cancellation semantics so browser/client stream cleanup is local-only by default:

useAgentChat({
  agent
});

By default, the browser is treated as a reconnectable observer of a server turn. Generic client-side stream abort/cleanup does not send cf_agent_chat_request_cancel, so the server turn can continue and be resumed later. Explicit stop() still sends cf_agent_chat_request_cancel and cancels the server turn.

For apps that intentionally want request-lifetime behavior, this adds:

cancelOnClientAbort?: boolean;

Set cancelOnClientAbort: true to make generic client abort/stream cleanup cancel the server turn.

What the issue actually was

This is not about a raw WebSocket close directly calling server-side abort.

The problematic path is one layer higher:

1. useAgentChat wraps AI SDK useChat.
2. AI SDK useChat owns a local active response with an AbortController.
3. WebSocketChatTransport.sendMessages() receives that signal as options.abortSignal, and also exposes a ReadableStream whose cancel() method can be called by the client stream lifecycle.
4. Before this PR, both paths used the same onAbort() handler.
5. That handler always sent cf_agent_chat_request_cancel.
6. The server correctly treated that frame as real server-turn cancellation.

So the server could not distinguish these two cases:

• the user/app explicitly clicked Stop and wanted to cancel the server turn
• the client-side response/stream was aborted or disposed as part of browser/React/AI SDK lifecycle

For Durable Object backed agents, the second case should often be recoverable via stream resumption. The browser can disappear or detach while the durable server turn continues and buffers chunks for a later reconnect.

What changed

• Added cancelOnClientAbort?: boolean to useAgentChat and WebSocketChatTransport.
  • Default is false: generic client abort/stream cancel is local-only.
  • true opts into request-lifetime behavior where generic client abort cancels the server turn.
• Removed the earlier durable / serverTurnCancellation API shape in favor of the clearer boolean toggle.
• Kept explicit useAgentChat().stop() as server-side cancellation regardless of cancelOnClientAbort.
• Updated docs and README for the default resumable semantics and the opt-in request-lifetime mode.

Follow-up changes from review

• Separated "active server turn is cancellable" from "local stream is attached" inside WebSocketChatTransport.
• Kept detached server turns explicitly cancellable after local-only client abort.
• Made explicit cancellation work for resumed streams created by reconnectToStream().
• Added support for explicitly cancelling fallback-observed server turns via observeServerTurn().
• Cleared stored cancellation state when the server later sends done for a detached turn.
• Avoided starting a new server turn when sendMessages() is called with an already-aborted signal.
• Added edge-case coverage for local-only abort, explicit stop after detach, resumed-stream stop, fallback-observed stop, and cancelOnClientAbort: true with both abort signals and stream.cancel().

Tests

• npm run test:workers -w @cloudflare/ai-chat -- ws-transport-abort.test.ts ws-transport-cancellation-policy.test.ts ws-transport-resume.test.ts
• npm run test:react -w @cloudflare/ai-chat -- use-agent-chat.test.tsx
• npm run check

Related

Fixes #1471